<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 3. Zend_Auth</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="index.html" title="Programmer's Reference Guide">
<link rel="prev" href="zend.acl.advanced.html" title="2.3. Advanced Use">
<link rel="next" href="zend.auth.adapter.dbtable.html" title="3.2. Database Table Authentication">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="section" href="zend.auth.html#zend.auth.introduction" title="3.1. Introduction">
<link rel="section" href="zend.auth.adapter.dbtable.html" title="3.2. Database Table Authentication">
<link rel="section" href="zend.auth.adapter.digest.html" title="3.3. Digest Authentication">
<link rel="section" href="zend.auth.adapter.http.html" title="3.4. HTTP Authentication Adapter">
<link rel="section" href="zend.auth.adapter.ldap.html" title="3.5. LDAP Authentication">
<link rel="section" href="zend.auth.adapter.openid.html" title="3.6. Open ID Authentication">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Chapter 3. Zend_Auth</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.acl.advanced.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="zend.auth.adapter.dbtable.html">Next</a>
</td>
</tr>
</table></div>
<div class="chapter" lang="en">
<div class="titlepage"><div><div><h2 class="title">
<a name="zend.auth"></a>Chapter 3. Zend_Auth</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="zend.auth.html#zend.auth.introduction">3.1. Introduction</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.auth.html#zend.auth.introduction.adapters">3.1.1. Adapters</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.html#zend.auth.introduction.results">3.1.2. Results</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.html#zend.auth.introduction.persistence">3.1.3. Identity Persistence</a></span></dt>
<dd><dl>
<dt><span class="sect3"><a href="zend.auth.html#zend.auth.introduction.persistence.default">3.1.3.1. Default Persistence in the PHP Session</a></span></dt>
<dt><span class="sect3"><a href="zend.auth.html#zend.auth.introduction.persistence.custom">3.1.3.2. Implementing Customized Storage</a></span></dt>
</dl></dd>
<dt><span class="sect2"><a href="zend.auth.html#zend.auth.introduction.using">3.1.4. Using Zend_Auth</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.auth.adapter.dbtable.html">3.2. Database Table Authentication</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.auth.adapter.dbtable.html#zend.auth.adapter.dbtable.introduction">3.2.1. Introduction</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.dbtable.html#zend.auth.adapter.dbtable.advanced.storing_result_row">3.2.2. Advanced Use: Persisting a DbTable Result Object</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.dbtable.html#zend.auth.adapter.dbtable.advanced.advanced_usage">3.2.3. Advanced Usage By Example</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.auth.adapter.digest.html">3.3. Digest Authentication</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.auth.adapter.digest.html#zend.auth.adapter.digest.introduction">3.3.1. Introduction</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.digest.html#zend.auth.adapter.digest.specifics">3.3.2. Specifics</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.digest.html#zend.auth.adapter.digest.identity">3.3.3. Identity</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.auth.adapter.http.html">3.4. HTTP Authentication Adapter</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.auth.adapter.http.html#zend.auth.adapter.http.introduction">3.4.1. Introduction</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.http.html#zend.auth.adapter.design_overview">3.4.2. Design Overview</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.http.html#zend.auth.adapter.configuration_options">3.4.3. Configuration Options</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.http.html#zend.auth.adapter.http.resolvers">3.4.4. Resolvers</a></span></dt>
<dd><dl><dt><span class="sect3"><a href="zend.auth.adapter.http.html#zend.auth.adapter.http.resolvers.file">3.4.4.1. File Resolver</a></span></dt></dl></dd>
<dt><span class="sect2"><a href="zend.auth.adapter.http.html#zend.auth.adapter.http.basic_usage">3.4.5. Basic Usage</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.auth.adapter.ldap.html">3.5. LDAP Authentication</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.auth.adapter.ldap.html#zend.auth.adapter.ldap.introduction">3.5.1. Introduction</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.ldap.html#zend.auth.adapter.ldap.usage">3.5.2. Usage</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.ldap.html#zend.auth.adapter.ldap.api">3.5.3. The API</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.ldap.html#zend.auth.adapter.ldap.server-options">3.5.4. Server Options</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.ldap.html#zend.auth.adapter.ldap.debugging">3.5.5. Collecting Debugging Messages</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.ldap.html#zend.auth.adapter.ldap.options-common-server-specific">3.5.6. Common Options for Specific Servers</a></span></dt>
<dd><dl>
<dt><span class="sect3"><a href="zend.auth.adapter.ldap.html#zend.auth.adapter.ldap.options-common-server-specific.active-directory">3.5.6.1. Options for Active Directory</a></span></dt>
<dt><span class="sect3"><a href="zend.auth.adapter.ldap.html#zend.auth.adapter.ldap.options-common-server-specific.openldap">3.5.6.2. Options for OpenLDAP</a></span></dt>
</dl></dd>
</dl></dd>
<dt><span class="sect1"><a href="zend.auth.adapter.openid.html">3.6. Open ID Authentication</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.auth.adapter.openid.html#zend.auth.adapter.openid.introduction">3.6.1. Introduction</a></span></dt>
<dt><span class="sect2"><a href="zend.auth.adapter.openid.html#zend.auth.adapter.openid.specifics">3.6.2. Specifics</a></span></dt>
</dl></dd>
</dl>
</div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.auth.introduction"></a>3.1. Introduction</h2></div></div></div>
<p>
        Zend_Auth provides an API for authentication and includes concrete authentication adapters for
        common use case scenarios.
    </p>
<p>
        Zend_Auth is concerned only with <span class="strong"><strong>authentication</strong></span> and not with
        <span class="strong"><strong>authorization</strong></span>. Authentication is loosely defined as determining
        whether an entity actually is what it purports to be (i.e., identification), based on some set of
        credentials. Authorization, the process of deciding whether to allow an entity access to, or to
        perform operations upon, other entities is outside the scope of Zend_Auth. For more information about
        authorization and access control with the Zend Framework, please see
        <a href="zend.acl.html" title="Chapter 2. Zend_Acl">Zend_Acl</a>.
    </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            The <code class="code">Zend_Auth</code> class implements the Singleton pattern - only one instance of the class is
            available - through its static <code class="code">getInstance()</code> method. This means that using the <code class="code">new</code>
            operator and the <code class="code">clone</code> keyword will not work with the <code class="code">Zend_Auth</code> class; use
            <code class="code">Zend_Auth::getInstance()</code> instead.
        </p></td></tr>
</table></div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.auth.introduction.adapters"></a>3.1.1. Adapters</h3></div></div></div>
<p>
            A Zend_Auth adapter is used to authenticate against a particular type of authentication service,
            such as LDAP, RDBMS, or file-based storage. Different adapters are likely to have vastly different
            options and behaviors, but some basic things are common among authentication adapters. For example,
            accepting authentication credentials (including a purported identity), performing queries against the
            authentication service, and returning results are common to Zend_Auth adapters.
        </p>
<p>
            Each Zend_Auth adapter class implements <code class="code">Zend_Auth_Adapter_Interface</code>. This interface defines one
            method, <code class="code">authenticate()</code>, that an adapter class must implement for performing an authentication
            query. Each adapter class must be prepared prior to calling <code class="code">authenticate()</code>. Such adapter
            preparation includes setting up credentials (e.g., username and password) and defining values for adapter-
            specific configuration options, such as database connection settings for a database table adapter.
        </p>
<p>
            The following is an example authentication adapter that requires a username and password to be set
            for authentication. Other details, such as how the authentication service is queried, have been
            omitted for brevity:

            </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Auth/Adapter/Interface.php';

class MyAuthAdapter implements Zend_Auth_Adapter_Interface
{
    /**
     * Sets username and password for authentication
     *
     * @return void
     */
    public function __construct($username, $password)
    {
        // ...
    }

    /**
     * Performs an authentication attempt
     *
     * @throws Zend_Auth_Adapter_Exception If authentication cannot be performed
     * @return Zend_Auth_Result
     */
    public function authenticate()
    {
        // ...
    }
}
            </pre>
<p>

            As indicated in its docblock, <code class="code">authenticate()</code> must return an instance of
            <code class="code">Zend_Auth_Result</code> (or of a class derived from <code class="code">Zend_Auth_Result</code>). If for some
            reason performing an authentication query is impossible, <code class="code">authenticate()</code> should throw
            an exception that derives from <code class="code">Zend_Auth_Adapter_Exception</code>.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.auth.introduction.results"></a>3.1.2. Results</h3></div></div></div>
<p>
            Zend_Auth adapters return an instance of <code class="code">Zend_Auth_Result</code> with
            <code class="code">authenticate()</code> in order to represent the results of an authentication attempt. Adapters
            populate the <code class="code">Zend_Auth_Result</code> object upon construction, so that the following four methods
            provide a basic set of user-facing operations that are common to the results of Zend_Auth adapters:
            </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                        <code class="code">isValid()</code> - returns true if and only if the result represents a
                        successful authentication attempt
                    </p></li>
<li><p>
                        <code class="code">getCode()</code> - returns a <code class="code">Zend_Auth_Result</code> constant identifier for
                        determining the type of authentication failure or whether success has occurred. This may be
                        used in situations where the developer wishes to distinguish among several authentication
                        result types. This allows developers to maintain detailed authentication result statistics,
                        for example. Another use of this feature is to provide specific, customized messages to
                        users for usability reasons, though developers are encouraged to consider the risks of
                        providing such detailed reasons to users, instead of a general authentication failure
                        message. For more information, see the notes below.
                    </p></li>
<li><p>
                        <code class="code">getIdentity()</code> - returns the identity of the authentication attempt
                    </p></li>
<li><p>
                        <code class="code">getMessages()</code> - returns an array of messages regarding a failed
                        authentication attempt
                    </p></li>
</ul></div>
<p>
        </p>
<p>
            A developer may wish to branch based on the type of authentication result in order to perform more
            specific operations. Some operations developers might find useful are locking accounts after too many
            unsuccessful password attempts, flagging an IP address after too many nonexistent identities are
            attempted, and providing specific, customized authentication result messages to the user. The following
            result codes are available:

            </p>
<pre class="programlisting">Zend_Auth_Result::SUCCESS
Zend_Auth_Result::FAILURE
Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
Zend_Auth_Result::FAILURE_UNCATEGORIZED
            </pre>
<p>

        </p>
<p>
            The following example illustrates how a developer may branch on the result code:

            </p>
<pre class="programlisting">&lt;?php
// inside of AuthController / loginAction
$result = $this-&gt;_auth-&gt;authenticate($adapter);

switch ($result-&gt;getCode()) {

    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
        /** do stuff for nonexistent identity **/
        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
        /** do stuff for invalid credential **/
        break;

    case Zend_Auth_Result::SUCCESS:
        /** do stuff for successful authentication **/
        break;

    default:
        /** do stuff for other failure **/
        break;
}
            </pre>
<p>

        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.auth.introduction.persistence"></a>3.1.3. Identity Persistence</h3></div></div></div>
<p>
            Authenticating a request that includes authentication credentials is useful per se, but it is also
            important to support maintaining the authenticated identity without having to present the
            authentication credentials with each request.
        </p>
<p>
            HTTP is a stateless protocol, however, and techniques such as cookies and sessions have been
            developed in order to facilitate maintaining state across multiple requests in server-side web
            applications.
        </p>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.auth.introduction.persistence.default"></a>3.1.3.1. Default Persistence in the PHP Session</h4></div></div></div>
<p>
                 By default, <code class="code">Zend_Auth</code> provides persistent storage of the identity from a successful
                 authentication attempt using the PHP session. Upon a successful authentication attempt,
                 <code class="code">Zend_Auth::authenticate()</code> stores the identity from the authentication result into
                 persistent storage. Unless configured otherwise, <code class="code">Zend_Auth</code> uses a storage class named
                 <code class="code">Zend_Auth_Storage_Session</code>, which, in turn, uses
                 <a href="zend.session.html" title="Chapter 39. Zend_Session">Zend_Session</a>. A custom class may instead be used by providing an
                 object that implements <code class="code">Zend_Auth_Storage_Interface</code> to
                 <code class="code">Zend_Auth::setStorage()</code>.
            </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
                    If automatic persistent storage of the identity is not appropriate for a particular use case, then
                    developers may forgo using the <code class="code">Zend_Auth</code> class altogether, instead using an adapter
                    class directly.
                </p></td></tr>
</table></div>
<div class="example">
<a name="zend.auth.introduction.persistence.default.example"></a><p class="title"><b>Example 3.1. Modifying the Session Namespace</b></p>
<div class="example-contents">
<p>
                    <code class="code">Zend_Auth_Storage_Session</code> uses a session namespace of <code class="code">'Zend_Auth'</code>. This
                    namespace may be overridden by passing a different value to the constructor of
                    <code class="code">Zend_Auth_Storage_Session</code>, and this value is internally passed along to the constructor
                    of <code class="code">Zend_Session_Namespace</code>. This should occur before authentication is attempted, since
                    <code class="code">Zend_Auth::authenticate()</code> performs the automatic storage of the identity.

                    </p>
<pre class="programlisting">&lt;?php
// Save a reference to the Singleton instance of Zend_Auth
require_once 'Zend/Auth.php';
$auth = Zend_Auth::getInstance();

// Use 'someNamespace' instead of 'Zend_Auth'
require_once 'Zend/Auth/Storage/Session.php';
$auth-&gt;setStorage(new Zend_Auth_Storage_Session('someNamespace'));

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// Authenticate, saving the result, and persisting the identity upon success
$result = $auth-&gt;authenticate($authAdapter);
                    </pre>
<p>

                </p>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.auth.introduction.persistence.custom"></a>3.1.3.2. Implementing Customized Storage</h4></div></div></div>
<p>
                Sometimes developers may need to use different identity persistence behavior than that provided by
                <code class="code">Zend_Auth_Storage_Session</code>. For such cases developers may simply implement
                <code class="code">Zend_Auth_Storage_Interface</code> and supply an instance of the class to
                <code class="code">Zend_Auth::setStorage()</code>.
            </p>
<div class="example">
<a name="zend.auth.introduction.persistence.custom.example"></a><p class="title"><b>Example 3.2. Using a Custom Storage Class</b></p>
<div class="example-contents">
<p>
                    In order to use an identity persistence storage class other than
                    <code class="code">Zend_Auth_Storage_Session</code>, a developer implements
                    <code class="code">Zend_Auth_Storage_Interface</code>:

                    </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Auth/Storage/Interface.php';

class MyStorage implements Zend_Auth_Storage_Interface
{
    /**
     * Returns true if and only if storage is empty
     *
     * @throws Zend_Auth_Storage_Exception If it is impossible to determine whether storage is empty
     * @return boolean
     */
    public function isEmpty()
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Returns the contents of storage
     *
     * Behavior is undefined when storage is empty.
     *
     * @throws Zend_Auth_Storage_Exception If reading contents from storage is impossible
     * @return mixed
     */
    public function read()
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Writes $contents to storage
     *
     * @param  mixed $contents
     * @throws Zend_Auth_Storage_Exception If writing $contents to storage is impossible
     * @return void
     */
    public function write($contents)
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Clears contents from storage
     *
     * @throws Zend_Auth_Storage_Exception If clearing contents from storage is impossible
     * @return void
     */
    public function clear()
    {
        /**
         * @todo implementation
         */
    }

}
                    </pre>
<p>

                </p>
<p>
                    In order to use this custom storage class, <code class="code">Zend_Auth::setStorage()</code> is invoked before an
                    authentication query is attempted:

                    </p>
<pre class="programlisting">&lt;?php
// Instruct Zend_Auth to use the custom storage class
Zend_Auth::getInstance()-&gt;setStorage(new MyStorage());

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// Authenticate, saving the result, and persisting the identity upon success
$result = Zend_Auth::getInstance()-&gt;authenticate($authAdapter);
                    </pre>
<p>

                </p>
</div>
</div>
<br class="example-break">
</div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.auth.introduction.using"></a>3.1.4. Using Zend_Auth</h3></div></div></div>
<p>
            There are two provided ways to use Zend_Auth adapters:
            </p>
<div class="orderedlist"><ol type="1">
<li><p>
                    indirectly, through <code class="code">Zend_Auth::authenticate()</code>
                </p></li>
<li><p>
                    directly, through the adapter's <code class="code">authenticate()</code> method
                </p></li>
</ol></div>
<p>
        </p>
<p>
            The following example illustrates how to use a Zend_Auth adapter indirectly, through the use of
            the <code class="code">Zend_Auth</code> class:

            </p>
<pre class="programlisting">&lt;?php
// Get a reference to the Singleton instance of Zend_Auth
require_once 'Zend/Auth.php';
$auth = Zend_Auth::getInstance();

// Set up the authentication adapter
$authAdapter = new MyAuthAdapter($username, $password);

// Attempt authentication, saving the result
$result = $auth-&gt;authenticate($authAdapter);

if (!$result-&gt;isValid()) {
    // Authentication failed; print the reasons why
    foreach ($result-&gt;getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Authentication succeeded; the identity ($username) is stored in the session
    // $result-&gt;getIdentity() === $auth-&gt;getIdentity()
    // $result-&gt;getIdentity() === $username
}
            </pre>
<p>
        </p>
<p>
            Once authentication has been attempted in a request, as in the above example, it is a simple
            matter to check whether a successfully authenticated identity exists:
            </p>
<pre class="programlisting">&lt;?php
$auth = Zend_Auth::getInstance();
if ($auth-&gt;hasIdentity()) {
    // Identity exists; get it
    $identity = $auth-&gt;getIdentity();
}
            </pre>
<p>
        </p>
<p>
            To remove an identity from persistent storage, simply use the <code class="code">clearIdentity()</code> method.
            This typically would be used for implementing an application "logout" operation:
            </p>
<pre class="programlisting">&lt;?php
Zend_Auth::getInstance()-&gt;clearIdentity();
            </pre>
<p>
        </p>
<p>
            When the automatic use of persistent storage is inappropriate for a particular use case, a
            developer may simply bypass the use of the <code class="code">Zend_Auth</code> class, using an adapter class
            directly. Direct use of an adapter class involves configuring and preparing an adapter object and
            then calling its <code class="code">authenticate()</code> method. Adapter-specific details are discussed in the
            documentation for each adapter. The following example directly utilizes
            <code class="code">MyAuthAdapter</code>:

            </p>
<pre class="programlisting">&lt;?php
// Set up the authentication adapter
$authAdapter = new MyAuthAdapter($username, $password);

// Attempt authentication, saving the result
$result = $authAdapter-&gt;authenticate();

if (!$result-&gt;isValid()) {
    // Authentication failed; print the reasons why
    foreach ($result-&gt;getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Authentication succeeded
    // $result-&gt;getIdentity() === $username
}
            </pre>
<p>
        </p>
</div>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.acl.advanced.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="zend.auth.adapter.dbtable.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">2.3. Advanced Use </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 3.2. Database Table Authentication</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
